home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / a_man / cat7 / stp.z / stp
Encoding:
Text File  |  2002-10-03  |  17.9 KB  |  331 lines
  1.  
  2.  
  3.  
  4. SSSSTTTTPPPP((((7777PPPP))))                                                                SSSSTTTTPPPP((((7777PPPP))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      stp - Scheduled Transfer Protocol
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssyyyyssss////ssssoooocccckkkkeeeetttt....hhhh>>>>
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnneeeettttiiiinnnneeeetttt////iiiinnnn....hhhh>>>>
  14.  
  15.      ssss ==== ssssoooocccckkkkeeeetttt((((AAAAFFFF____SSSSTTTTPPPP,,,, SSSSOOOOCCCCKKKK____SSSSEEEEQQQQPPPPAAAACCCCKKKKEEEETTTT,,,, IIIIPPPPPPPPRRRROOOOTTTTOOOO____SSSSTTTTPPPP))));;;;
  16.  
  17. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      STP is a data transfer protocol that uses small control messages to pre-
  19.      arrange data movement. Buffers are allocated at the sending and the
  20.      receiving end before the data transmission, allowing full-rate, non-
  21.      congesting data flow between the end devices.  The control and data may
  22.      use different physical media, or may share a single physical medium.
  23.  
  24.      The _r_e_a_d(2) or _r_e_c_v(2) and _w_r_i_t_e(2) or _s_e_n_d(2) system calls should be
  25.      used to transfer data over STP sockets. By the very nature of STP, a send
  26.      operation on an STP socket must have a corresponding receive at the peer
  27.      in order for progress to be made.  This is because STP is fundamentally a
  28.      ``no-copy'' protocol, where transfers are a-priori scheduled to occur
  29.      directly from user-space to user-space: there is no intermediate copy of
  30.      user-payload into kernel-space.  If the user buffer is not aligned on a
  31.      double word boundry it may be realigned inside kernel memory resulting in
  32.      a bcopy of user data depending on the type of physical NIC.
  33.  
  34.      The _s_e_n_d_m_s_g(2) and _r_e_c_v_m_s_g(2) system calls may be used in a restricted
  35.      fashion for scatter-gather operations.  The mmmmssssgggg____nnnnaaaammmmeeee and mmmmssssgggg____nnnnaaaammmmeeeelllleeeennnn
  36.      fields in the mmmmssssgggghhhhddddrrrr structure are ignored.  The mmmmssssgggg____iiiioooovvvv field has the
  37.      following restrictions.  If the mmmmssssgggg____iiiioooovvvvlllleeeennnn == 1 then the vector (buffer)
  38.      being sent must only meet the device alignment restrictions.  If mmmmssssgggg____lllleeeennnn
  39.      is greater than one then the mmmmssssgggg____iiiioooovvvv[[[[0000]]]]....iiiioooovvvv____bbbbaaaasssseeee must end on a 2222^^^^SSSSTTTT____BBBBUUUUFFFFSSSSZZZZ
  40.      boundry. The middle vectors mmmmssssgggg____iiiioooovvvv[[[[1111]]]]....iiiioooovvvv____bbbbaaaasssseeee thru mmmmssssgggg____iiiioooovvvv[[[[mmmmssssgggg____iiiioooovvvvlllleeeennnn----
  41.      2222]]]]....iiiioooovvvv____bbbbaaaasssseeee must be of length 2222^^^^SSSSTTTT____BBBBUUUUFFFFSSSSZZZZ if they exist.  The last vector
  42.      mmmmssssgggg____iiiioooovvvv[[[[mmmmssssgggg____iiiioooovvvvlllleeeennnn----1111]]]]....iiiioooovvvv____bbbbaaaasssseeee must start on a 2222^^^^SSSSTTTT____BBBBUUUUFFFFSSSSZZZZ boundy.  The
  43.      first, middle and last vector must also meet the device alignment
  44.      restrictions. The msghdr may contain zero length vectors which are
  45.      removed before sending.
  46.  
  47.      STP supports several socket options which can be tested with
  48.      _g_e_t_s_o_c_k_o_p_t(_2) and manipulated with _s_e_t_s_o_c_k_o_p_t(_2).  These options are
  49.      defined in <_n_e_t_i_n_e_t/_s_t._h>.
  50.  
  51.  
  52.      ST_CTS_OUTSTD
  53.           Tells the ST socket how many outstanding clear-to-sends (CTS-es) the
  54.           initiator of a write()/send() can handle. Other things remaining
  55.           equal, increasing this value pipelines the data transfer, and is
  56.           expected to increase bandwidth.  The default value for ST sockets is
  57.           128. The data type for the {set|get}socketopt is an unsigned short.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSTTTTPPPP((((7777PPPP))))                                                                SSSSTTTTPPPP((((7777PPPP))))
  71.  
  72.  
  73.  
  74.      ST_BLKSZ
  75.           Modifies the BlockSize parameter, as defined in the ST protocol
  76.           standard. Other things remaining equal, a larger blocksize is
  77.           expected to increase bandwidth. The parameter is specified as a
  78.           power of 2. The default block size is 24 (16 MB). The maximum block
  79.           size is 24.  The data type for the {set|get}socketopt is an unsigned
  80.           short.
  81.  
  82.  
  83.      ST_BUFSZ
  84.           The size of buffers to use for the transfer. As explained in the ST
  85.           protocol specification, this information is exchanged between the
  86.           initiator and the responder of a transfer during connection set-up.
  87.           Other things remaining equal, a larger bufsize is expected to
  88.           increase bandwidth. Note that setting a bufsize of N bytes makes
  89.           sense if and only if the user buffer's physical memory fragments are
  90.           each of size at least N bytes. The parameter is specified as a power
  91.           of 2. The default bufsize is 14 (16 Kbytes).  The data type for the
  92.           {set|get}socketopt is an unsigned int.
  93.  
  94.  
  95.      ST_STUSZ
  96.           The default size of the Scheduled Transfer Unit (STU) to be
  97.           transmitted.  (STU is similar to an MTU - Maximum Transfer Unit - on
  98.           most networks.) This can be throttled down by the other end-point
  99.           per the STP specification. The parameter is specified as a power of
  100.           2. Default size is 24 (16777216 bytes) on GSN and 10 (1024 bytes) on
  101.           all versions of ethernet. Also note that the actual STU size is the
  102.           minimum of the ST_BLKSZ and ST_STUSZ parameters, per the STP
  103.           specification.  The data type for the {set|get}socketopt is an
  104.           unsigned int.
  105.  
  106.  
  107.      ST_OUT_VCNUM
  108.           The virtual circuit to be used for payload packets -- can be set to
  109.           2 or 3. The default VC used for payload packets is 3.  _[[[[_TTTT_hhhh_iiii_ssss
  110.           _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr _mmmm_aaaa_kkkk_eeee_ssss _ssss_eeee_nnnn_ssss_eeee _ffff_oooo_rrrr _GGGG_iiii_gggg_aaaa_bbbb_yyyy_tttt_eeee _SSSS_yyyy_ssss_tttt_eeee_mmmm _NNNN_eeee_tttt_wwww_oooo_rrrr_kkkk _hhhh_aaaa_rrrr_dddd_wwww_aaaa_rrrr_eeee _oooo_nnnn_llll_yyyy_...._]]]]
  111.           The data type for the {set|get}socketopt is an unsigned char.
  112.  
  113.  
  114.      ST_TX_SPRAY_WIDTH
  115.           The size of spray to be used for sending payload. This parameter can
  116.           be set to 1, 2, 4, or 8. The default spray size used for a send is 1
  117.           ("no spray").  _[[[[_SSSS_eeee_tttt_tttt_iiii_nnnn_gggg _tttt_hhhh_eeee _ssss_pppp_rrrr_aaaa_yyyy _wwww_iiii_dddd_tttt_hhhh _ssss_hhhh_oooo_uuuu_llll_dddd _bbbb_eeee _dddd_oooo_nnnn_eeee _vvvv_eeee_rrrr_yyyy
  118.           _cccc_aaaa_rrrr_eeee_ffff_uuuu_llll_llll_yyyy_,,,, _ssss_iiii_nnnn_cccc_eeee _iiii_tttt _iiii_ssss _eeee_aaaa_ssss_yyyy _tttt_oooo _gggg_eeee_tttt _gggg_aaaa_rrrr_bbbb_llll_eeee_dddd _dddd_aaaa_tttt_aaaa _oooo_nnnn _aaaa _tttt_rrrr_aaaa_nnnn_ssss_ffff_eeee_rrrr _iiii_ffff _aaaa_llll_llll
  119.           _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr_ssss _oooo_ffff _tttt_hhhh_eeee _ssss_pppp_rrrr_aaaa_yyyy _aaaa_rrrr_eeee _nnnn_oooo_tttt _eeee_xxxx_aaaa_cccc_tttt_llll_yyyy _rrrr_iiii_gggg_hhhh_tttt_....  _TTTT_hhhh_iiii_ssss _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr _mmmm_aaaa_kkkk_eeee_ssss
  120.           _ssss_eeee_nnnn_ssss_eeee _ffff_oooo_rrrr _tttt_hhhh_eeee _GGGG_iiii_gggg_aaaa_bbbb_yyyy_tttt_eeee _SSSS_yyyy_ssss_tttt_eeee_mmmm _NNNN_eeee_tttt_wwww_oooo_rrrr_kkkk _hhhh_aaaa_rrrr_dddd_wwww_aaaa_rrrr_eeee _oooo_nnnn_llll_yyyy_...._]]]]  The data type
  121.           for the {set|get}socketopt is an unsigned char.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSTTTTPPPP((((7777PPPP))))                                                                SSSSTTTTPPPP((((7777PPPP))))
  137.  
  138.  
  139.  
  140.      ST_RX_SPRAY_WIDTH
  141.           The size of spray to be used for receiving payload. This parameter
  142.           can be set to 1, 2, 4, or 8. The default spray size used for a
  143.           receive is 1 ("no spray").  _[[[[_SSSS_eeee_tttt_tttt_iiii_nnnn_gggg _tttt_hhhh_eeee _ssss_pppp_rrrr_aaaa_yyyy _wwww_iiii_dddd_tttt_hhhh _ssss_hhhh_oooo_uuuu_llll_dddd _bbbb_eeee _dddd_oooo_nnnn_eeee
  144.           _vvvv_eeee_rrrr_yyyy _cccc_aaaa_rrrr_eeee_ffff_uuuu_llll_llll_yyyy_,,,, _ssss_iiii_nnnn_cccc_eeee _iiii_tttt _iiii_ssss _eeee_aaaa_ssss_yyyy _tttt_oooo _gggg_eeee_tttt _gggg_aaaa_rrrr_bbbb_llll_eeee_dddd _dddd_aaaa_tttt_aaaa _oooo_nnnn _aaaa _tttt_rrrr_aaaa_nnnn_ssss_ffff_eeee_rrrr
  145.           _iiii_ffff _aaaa_llll_llll _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr_ssss _oooo_ffff _tttt_hhhh_eeee _ssss_pppp_rrrr_aaaa_yyyy _aaaa_rrrr_eeee _nnnn_oooo_tttt _eeee_xxxx_aaaa_cccc_tttt_llll_yyyy _rrrr_iiii_gggg_hhhh_tttt_....  _TTTT_hhhh_iiii_ssss
  146.           _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr _mmmm_aaaa_kkkk_eeee_ssss _ssss_eeee_nnnn_ssss_eeee _ffff_oooo_rrrr _tttt_hhhh_eeee _GGGG_iiii_gggg_aaaa_bbbb_yyyy_tttt_eeee _SSSS_yyyy_ssss_tttt_eeee_mmmm _NNNN_eeee_tttt_wwww_oooo_rrrr_kkkk _hhhh_aaaa_rrrr_dddd_wwww_aaaa_rrrr_eeee
  147.           _oooo_nnnn_llll_yyyy_...._]]]]  The data type for the {set|get}socketopt is an unsigned
  148.           char.
  149.  
  150.  
  151.      ST_USE_APPEND_PORT
  152.           This allows the user to specify to the STP stack to use an append
  153.           data port.  This parameter can be 0 to use normal port or 1 to have
  154.           it be an append port.  _[[[[_TTTT_hhhh_iiii_ssss _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr _mmmm_aaaa_kkkk_eeee_ssss _ssss_eeee_nnnn_ssss_eeee _ffff_oooo_rrrr _tttt_hhhh_eeee _GGGG_iiii_gggg_aaaa_bbbb_yyyy_tttt_eeee
  155.           _SSSS_yyyy_ssss_tttt_eeee_mmmm _NNNN_eeee_tttt_wwww_oooo_rrrr_kkkk _hhhh_aaaa_rrrr_dddd_wwww_aaaa_rrrr_eeee _oooo_nnnn_llll_yyyy_...._]]]]  The data type for the
  156.           {set|get}socketopt is an unsigned char.
  157.  
  158.  
  159.      ST_MAP_PORT_DIRECT
  160.           This allows the user to specify a hardware port to use directly
  161.           instead of having the STP stack assign one.  This parameter can be 0
  162.           to let the STP stack choose a hardware port or 1 to have it user
  163.           specified.  The user specified value is the port to which the socket
  164.           is bound.  _[[[[_TTTT_hhhh_iiii_ssss _pppp_aaaa_rrrr_aaaa_mmmm_eeee_tttt_eeee_rrrr _mmmm_aaaa_kkkk_eeee_ssss _ssss_eeee_nnnn_ssss_eeee _ffff_oooo_rrrr _tttt_hhhh_eeee _GGGG_iiii_gggg_aaaa_bbbb_yyyy_tttt_eeee _SSSS_yyyy_ssss_tttt_eeee_mmmm
  165.           _NNNN_eeee_tttt_wwww_oooo_rrrr_kkkk _hhhh_aaaa_rrrr_dddd_wwww_aaaa_rrrr_eeee _oooo_nnnn_llll_yyyy_...._]]]]  The data type for the {set|get}socketopt is
  166.           an unsigned char.
  167.  
  168.  
  169. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  170.        int sd;        /* socket file descriptor */
  171.        u_char st_port_spray =  1;
  172.        uint     st_port_stusz = 14;
  173.        uint     st_port_bufsz = 14;
  174.        ushort st_port_blksz = 24;
  175.  
  176.        ... OPEN SOCKET ...
  177.  
  178.        if(setsockopt(sd, IPPROTO_STP, ST_TX_SPRAY_WIDTH,
  179.                      &st_port_spray, sizeof(st_port_spray)) < 0) {
  180.          perror("setsockopt ST_TX_SPRAY_WIDTH failed");
  181.          exit(-1);
  182.        }
  183.  
  184.        if(setsockopt(sd, IPPROTO_STP, ST_RX_SPRAY_WIDTH,
  185.                      &st_port_spray, sizeof(st_port_spray)) < 0) {
  186.          perror("setsockopt ST_RX_SPRAY_WIDTH failed");
  187.          exit(-1);
  188.        }
  189.  
  190.        if (setsockopt(sd, IPPROTO_STP, ST_STUSZ,
  191.                       &st_port_stusz, sizeof(st_port_stusz)) < 0) {
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSTTTTPPPP((((7777PPPP))))                                                                SSSSTTTTPPPP((((7777PPPP))))
  203.  
  204.  
  205.  
  206.          perror("setsockopt ST_STUSZ failed");
  207.          exit(-1);
  208.        }
  209.  
  210.        if (setsockopt(sd, IPPROTO_STP, ST_BUFSZ,
  211.                       &st_port_bufsz, sizeof(st_port_bufsz)) < 0) {
  212.          perror("setsockopt ST_BUFSZ failed");
  213.          exit(-1);
  214.        }
  215.  
  216.        if (setsockopt(sd, IPPROTO_STP, ST_BLKSZ,
  217.                       &st_port_blksz, sizeof(st_port_blksz)) < 0) {
  218.          perror("setsockopt ST_BLKSZ failed");
  219.          exit(-1);
  220.        }
  221.  
  222.  
  223.  
  224. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  225.      A socket operation may fail with one of the following errors returned:
  226.  
  227.  
  228.      [EISCONN]      when trying to establish a connection on a socket which
  229.                     already has one, or when trying to send a datagram with
  230.                     the destination address specified and the socket is
  231.                     already connected.
  232.  
  233.  
  234.      [ENOTCONN]     when trying to send a datagram, but no destination address
  235.                     is specified, and the socket hasn't been connected.
  236.  
  237.  
  238.      [EHOSTUNREACH] The desination address can not be reached.  Check
  239.                     harp/arp.
  240.  
  241.  
  242.      [EPIPE]        The socket had an error and the connection was torn down.
  243.  
  244.  
  245.      [ECONNABORTED] The socket had an error and the connection was torn down.
  246.  
  247.  
  248.      [EADDRNOTAVAIL]
  249.                     when an attempt is made to create a socket with a network
  250.                     address for which no network interface exists.
  251.  
  252.  
  253.      [ETIMEDOUT]    A keepalive timer or send/recv timer has expired and the
  254.                     operation was aborted.
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. SSSSTTTTPPPP((((7777PPPP))))                                                                SSSSTTTTPPPP((((7777PPPP))))
  269.  
  270.  
  271.  
  272.      [EINVAL]       The page size of buffers passed to send/recv is too large
  273.                     or small based on the  specified blocksize.  This can also
  274.                     be received when an invalid socket option is attempted.
  275.  
  276.  
  277.      [EPROTONOSUPPORT]
  278.                     Trying to use STP on a device for which it is not
  279.                     supported.
  280.  
  281.  
  282.      [EOPNOTSUPP]   Most likely trying to send/recv OOB data which is not
  283.                     supported.
  284.  
  285.  
  286.      [ENOBUFS]      The system has run out of memory for an internal data
  287.                     structure.
  288.  
  289.  
  290.      [ENOMEM]       The system has run out of memory for an internal data
  291.                     structure or the blocksize is greater than the maxdmasz
  292.                     (maximum DMA size - see systune(1M)).
  293.  
  294.  
  295.      [EFAULT]       Tried to send/recv in a buffer that is not owned by the
  296.                     application.
  297.  
  298.  
  299. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  300.      send(2), recv(2), intro(3), write(2), read(2), systune(1M)
  301.      _I_R_I_X _N_e_t_w_o_r_k _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e,
  302.      ANSI T11.1/Project 1245-D: Scheduled Transfer Protocol specifications at
  303.      http://www.hippi.org
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.